HAL I2C migration: List of applicable concepts

This section provides information about the HAL I2C applicable architecture concepts.

Concepts for I2C

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate initialization and configuration functions: HAL_I2C_Init: initializes the handle and links it to an I2C instance. HAL_I2C_SetConfig: configure the I2C according to the user parameters.
Removal and conversion of init structure to configuration structure	The initialization structure has been removed and moved into hal_i2c_config_t configuration structure.
Renaming of the handle structure	The handle structure has been renamed to hal_i2c_handle_t.
Renaming unitary init structures	The structure I2C_InitTypeDef is no longer available and has been replaced by hal_i2c_config_t.
Remove MspInit and MspDeInit callbacks	HAL_I2C_MspInit and HAL_I2C_MspDeInit are no longer available and have been replaced by a user sequence to initialize and configure the I2C.
Unitary configuration APIs	New APIs are available to get and set I2C features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	The __HAL_LINKDMA macro is no longer provided and new functions HAL_I2C_SetTxDMA and HAL_I2C_SetRxDMA are provided to link an I2C HAL handle to a DMA HAL handle.
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: HAL_I2C_SetUserData and HAL_I2C_GetUserData.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each I2C event. These functions are used to register callback functions for different I2C events.
Introduce specialized IRQ handlers	HAL_I2C_EV_IRQHandler and HAL_I2C_ER_IRQHandler are still available in HAL2.
HAL implementation with LL inline functions	HAL I2C APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL I2C define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL I2C driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The I2C state machine is reworked to ensure transitions of the peripheral functional states
Revised and optimized HAL API status returns	The HAL I2C functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	The HAL error handling mechanisms have been redesigned to improve the detection, reporting, and handling of errors. This provides more detailed and consistent error information.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL I2C driver have been removed and replaced by _t.
Replaced multi-line macros with inline functions	For the HAL I2C driver, large macros have been replaced by inline functions to maintain code consistency, improve readability, and benefit from compiler optimization. Inline functions also offer better support for debugging and strict type management, reducing the risk of errors.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macro.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL I2C header file remains and all macros, define statements, and functions from hal_i2c_ex.h have been moved to hal_i2c.h.
Provide RTOS-compatible acquire/release bus services for communication peripheral drivers.	Implementing functions to manage the access to communication buses like I2C in a multi-tasking environment. These services ensure that only one task can use the bus at a time, preventing conflicts and ensuring data integrity. The acquire function locks the bus for a task, while the release function unlocks it, allowing other tasks to use the bus.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including I2C instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL I2C functions start with HAL_I2C. All HAL I2C enumerations and structures start with hal_i2c.

Other HAL I2C changes

Concept	Consideration
Disable stretch mode and optimize the hal code.	Stretch mode is now controlled via the dedicated enable, disable, and status (is-enabled) functions.
The I2C peripheral is enabled only during process execution: Power consumption improvement.	Enable the I2C peripheral at the start of the processes and disable it upon their completion, rather than disabling it at the beginning of a configuration function and re-enabling it at the end of that function.